---
id: how-to-deploy
sidebar_label: Deploying Your Assistant
title: Deploying Your Rasa Assistant
description: How to deploy your Rasa Assistant with Docker Compose or Kubernetes/Openshift
abstract: This page explains when and how to deploy an assistant built with Rasa.
  It will allow you to make your assistant available to users and set you up with a production-ready environment.
---
<!-- this file is version specific, do not use `@site/...` syntax -->
import variables from './variables.json';

## When to Deploy Your Assistant

The best time to deploy your assistant and make it available to test users is once it can handle the most
important happy paths or is what we call a [minimum viable assistant](./glossary.mdx).

The recommended deployment methods described below make it easy to share your assistant
with test users via the [share your assistant feature in
Rasa X](https://rasa.com/docs/rasa-x/user-guide/share-assistant#share-your-bot).
Then, when you're ready to make your assistant available via one or more [Messaging and Voice Channels](./messaging-and-voice-channels.mdx),
you can easily add them to your existing deployment set up.

## Recommended Deployment Methods

The recommended way to deploy an assistant is using either the Server Quick-Install or Helm Chart
options we support. Both deploy Rasa X and your assistant. They are the easiest ways to deploy your assistant,
allow you to use Rasa X to view conversations and turn them into training data, and are production-ready.
For more details on deployment methods see the [Rasa X Installation Guide](https://rasa.com/docs/rasa-x/installation-and-setup/installation-guide/).

### Server Quick-Install

The Server Quick-Install script is the easiest way to deploy Rasa X and your assistant. It installs a Kubernetes
cluster on your machine with sensible defaults, getting you up and running in one command.

* Default: Make sure you meet the [OS Requirements](https://rasa.com/docs/rasa-x/installation-and-setup/install/quick-install-script/#hardware-os-requirements),
  then run:

  ```bash
  curl -s get-rasa-x.rasa.com | sudo bash
  ```

* Custom: See [Customizing the Script](https://rasa.com/docs/rasa-x/installation-and-setup/customize/#server-quick-install)
  and the [Server Quick-Install docs](https://rasa.com/docs/rasa-x/installation-and-setup/install/quick-install-script) docs.

### Helm Chart

For assistants that will receive a lot of user traffic, setting up a Kubernetes or Openshift deployment via
our Helm charts is the best option. This provides a scalable architecture that is also straightforward to deploy.
However, you can also customize the Helm charts if you have specific requirements.

* Default: Read the [Helm Chart Installation](https://rasa.com/docs/rasa-x/installation-and-setup/install/helm-chart/) docs.

* Custom: Read the above, as well as the [Advanced Configuration](https://rasa.com/docs/rasa-x/installation-and-setup/customize/#helm-chart)
  documentation, and customize the [open source Helm charts](https://github.com/RasaHQ/rasa-x-helm) to your needs.

## Deploying a Rasa Open Source Assistant

While the above deployment methods involve deploying an assistant with Rasa X, the following instructions describe how to deploy a Rasa Open Source server only
by using the [Rasa Helm Chart](https://github.com/RasaHQ/helm-charts/tree/main/charts/rasa) in a scalable cluster environment using OpenShift or Kubernetes (K8S).

### Cluster Requirements

To install the Rasa Helm chart, you need an existing
[Kubernetes cluster](https://kubernetes.io/) or [OpenShift cluster](https://www.openshift.com/).
Setting up a Kubernetes / OpenShift cluster can be tedious, hence we
recommend to get a managed cluster from a cloud provider like
[Google Cloud](https://cloud.google.com/kubernetes-engine),
[DigitalOcean](https://www.digitalocean.com/products/kubernetes/),
[Microsoft Azure](https://azure.microsoft.com/en-us/services/kubernetes-service/), or
[Amazon EKS](https://aws.amazon.com/eks/).

:::note
The Rasa Helm chart is open source and available in the
[helm-charts repository](https://github.com/rasahq/helm-charts).
Please
[create an issue](https://github.com/RasaHQ/helm-charts/issues/new) in this
repository if you discover bugs or have suggestions for improvements.

:::


### Installation Requirements

1. Check that you have installed the Kubernetes or OpenShift command line
   interface (CLI). You can check this using the following command:

   <Tabs values={[{"label": "Kubernetes", "value": "kubernetes"}, {"label": "OpenShift", "value": "openshift"}]} defaultValue="kubernetes">
     <TabItem value="kubernetes">

     ```bash
     kubectl version --short --client

     # The output should be similar to this
     # Client Version: v1.19.11
     ```

     </TabItem>
     <TabItem value="openshift">

     ```bash
     oc version --client

     # The output should be similar to this
     # Client Version: 4.7.13
     ```

     </TabItem>
   </Tabs>

   If this command resulted in an error, please install the
   [Kubernetes CLI](https://kubernetes.io/docs/tasks/tools/install-kubectl/) or the
   [OpenShift CLI](https://docs.openshift.com/container-platform/4.7/cli_reference/openshift_cli/getting-started-cli.html#installing-openshift-cli)
   depending on the cluster you’re using.

2. Make sure that the Kubernetes / OpenShift CLI is correctly connected to
   your cluster. You can do so by using the following commands:

   <Tabs values={[{"label": "Kubernetes", "value": "kubernetes"}, {"label": "OpenShift", "value": "openshift"}]} defaultValue="kubernetes">
     <TabItem value="kubernetes">

     ```bash
     kubectl version --short

     # The output should be similar to this
     # Client Version: v1.19.11
     # Server Version: v1.19.10
     ```

     </TabItem>
     <TabItem value="openshift">

     ```bash
     oc version

     # The output should be similar to this
     # Client Version: 4.7.13
     # Kubernetes Version: v1.20.0+df9c838
     ```

     </TabItem>
   </Tabs>

   If you get an error when executing the command, you are not connected to your
   cluster. To get the command to connect to the cluster please consult your cluster’s
   admin or the documentation of your cloud provider.

3. Make sure you have the [Helm CLI](https://helm.sh/docs/intro/install/)
   installed. To check this, run:

   ```bash
   helm version --short

   # The output should be similar to this
   # v3.6.0+g7f2df64
   ```

   If this command leads to an error, please install the
   [Helm CLI](https://helm.sh/docs/intro/install/).

   In case you are using a version `<3.5` of Helm, please update to Helm version
   `>=3.5`.

### Installation

#### 1. Create Namespace

We recommend installing Rasa Open Source in a separate
[namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
to avoid interfering with existing cluster deployments. To create a new namespace
run the following command:

<Tabs values={[{"label": "Kubernetes", "value": "kubernetes"}, {"label": "OpenShift", "value": "openshift"}]} defaultValue="kubernetes">
  <TabItem value="kubernetes">

  ```bash
  kubectl create namespace <your namespace>
  ```

  </TabItem>
  <TabItem value="openshift">

  ```bash
  oc create namespace <your namespace>
  ```

  </TabItem>
</Tabs>

#### 2. Create Values File

Prepare an empty file called `rasa-values.yml` which will include all your custom
configuration for the installation with Helm.

All available values you can find in [the Rasa helm chart repository](https://github.com/RasaHQ/helm-charts/tree/main/charts/rasa#values).

:::note
The default configuration of the Rasa chart deploys a Rasa Open Source Server, downloads a model, and serves the downloaded model.
Visit [the Rasa helm chart repository](https://github.com/RasaHQ/helm-charts/tree/main/charts/rasa#quick-start) to check out more examples of configuration.

:::

#### 3. Loading an initial model

The first time you install Rasa, you may not have a model server available yet, or you may want an lightweight model for testing the deployment.
For this purpose, you can choose between training or downloading an initial model. By default, the Rasa chart downloads an example model from GitHub.
To use this option, you don't have to change anything.

If you want to define an existing model to download from a URL you define instead, update your `rasa-values.yaml` with the URL according to the following configuration:

  ```yaml
  applicationSettings:
    initialModel: "https://github.com/RasaHQ/rasa-x-demo/blob/master/models/model.tar.gz?raw=true"
  ```
:::note
The URL for the initial model download has to point to a tar.gz file and must not require authentication.

:::

If you want to train an initial model you can do this by setting the `applicationSettings.trainInitialModel` to `true`.
It creates a init container that trains a model based on data located in the `/app` directory. If the `/app` directory is empty it creates a new project.
You can find an example that shows how to download data files from a git repository and train an initial model in the Rasa helm charts [examples](https://github.com/RasaHQ/helm-charts/blob/main/examples/rasa/train-model-helmfile.yaml).

#### 4. Deploy Rasa Open Source Assistant

Run the following commands:

```bash
# Add the repository which contains the Rasa Helm chart
helm repo add rasa https://helm.rasa.com

# Deploy Rasa Open Source
helm install \
    --namespace <your namespace> \
    --values rasa-values.yml \
    <release name> \
    rasa/rasa
```

:::note
**OpenShift only**: If the deployment fails and `oc get events` returns
`1001 is not an allowed group spec.containers[0].securityContext.securityContext.runAsUser`,
re-run the installation command with the following values:

```yaml
postgresql:
  volumePermissions:
    securityContext:
      runAsUser: "auto"
  securityContext:
    enabled: false
  shmVolume:
    chmod:
      enabled: false
nginx:
  image:
    name: nginxinc/nginx-unprivileged
    port: 8080
```

Then wait until the deployment is ready. If you want to check on its status, the following command
will block until the Rasa deployment is ready:

<Tabs values={[{"label": "Kubernetes", "value": "kubernetes"}, {"label": "OpenShift", "value": "openshift"}]} defaultValue="kubernetes">
  <TabItem value="kubernetes">

  ```bash
  kubectl --namespace <your namespace> \
      wait \
      --for=condition=available \
      --timeout=20m \
      --selector app.kubernetes.io/instance=<release name> \
      deployment
  ```

  </TabItem>
  <TabItem value="openshift">

  ```bash
  oc --namespace <your namespace> \
      wait \
      --for=condition=available \
      --timeout=20m \
      --selector app.kubernetes.io/instance=<release name> \
      deployment
  ```

  </TabItem>
</Tabs>

:::


#### 5. Access Rasa Open Source Assistant

By default the Rasa deployment is exposed via the `rasa` (`<release name>`) service and accessible only within a Kubernetes cluster. You can get
the IP address using this command:

<Tabs values={[{"label": "Kubernetes", "value": "kubernetes"}, {"label": "OpenShift", "value": "openshift"}]} defaultValue="kubernetes">
  <TabItem value="kubernetes">

  ```bash
    export SERVICE_PORT=$(kubectl get --namespace <your namespace> -o jsonpath="{.spec.ports[0].port}" services <release name>)
    kubectl port-forward --namespace <your namespace> svc/<release name> ${SERVICE_PORT}:${SERVICE_PORT} &
  ```

  </TabItem>
  <TabItem value="openshift">

  ```bash
    export SERVICE_PORT=$(oc get --namespace <your namespace> -o jsonpath="{.spec.ports[0].port}" services <release name>)
    oc port-forward --namespace <your namespace> svc/<release name> ${SERVICE_PORT}:${SERVICE_PORT} &
  ```

  </TabItem>
</Tabs>

You can then access the deployment on `http://127.0.0.1:${SERVICE_PORT}`

Visit [the Rasa helm chart README](https://github.com/RasaHQ/helm-charts/tree/main/charts/rasa#exposing-the-rasa-deployment-to-the-public) to learn other ways to expose your deployment.

#### Next Steps

Visit [the Rasa helm chart repository](https://github.com/RasaHQ/helm-charts/tree/main/charts/rasa) where you can find examples of configuration and learn how to e.g. integrate your Rasa Open Source deployment with Rasa X.

## Alternative Deployment Methods

### Docker Compose

You can also run Rasa X in a Docker Compose setup, without the cluster environment. We have an install script
for doing so, as well as manual instructions for any custom setups.

* Default: Read the [Docker Compose Install Script](https://rasa.com/docs/rasa-x/installation-and-setup/install/docker-compose/#docker-compose-install-script) docs or watch the [Masterclass Video](https://www.youtube.com/watch?v=IUYdwy8HPVc) on deploying Rasa X.

* Custom: Read the [Docker Compose Manual Install](https://rasa.com/docs/rasa-x/installation-and-setup/install/docker-compose/#docker-compose-manual-install) documentation for full customization options.

### Rasa Open Source Only Deployment

It is also possible to deploy a Rasa assistant without Rasa X using Docker Compose. To do so, you can build your
Rasa Assistant locally or in Docker. Then you can deploy your model in Docker Compose.

* [Building a Rasa Assistant Locally](./playground.mdx)

* [Building a Rasa Assistant in Docker](./docker/building-in-docker.mdx)

* [Deploying a Rasa Open Source Assistant in Docker Compose](./docker/deploying-in-docker-compose.mdx)


## Deploying Your Action Server

### Building an Action Server Image

If you build an image that includes your action code and store it in a container registry, you can run it
as part of your deployment, without having to move code between servers.
In addition, you can add any additional dependencies of systems or Python libraries
that are part of your action code but not included in the base `rasa/rasa-sdk` image.

#### Automating your Action Server Image Builds

In addition to a manually creating a new Action Server image, you can use the [Rasa Action Server GitHub Action](https://github.com/RasaHQ/action-server-gha) to automate image builds.
If GitHub Actions are new to you, it might be helpful to get familiar with [GitHub Actions Documentation](https://docs.github.com/en/actions).

The following steps assume that you already created a GitHub repository and you have a DockerHub account.

To create a workflow for building and pushing a Docker image into a DockerHub registry:

1. Add GitHub Secrets with your DockerHub login name and password.
   You can find details on how to create encrypted secrets for a repository
   in the [Github docs](https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository)

   The example uses the following secrets:
   - `DOCKER_HUB_LOGIN` - a login name for DockerHub
   - `DOCKER_HUB_PASSWORD` - a password for DockerHub

2. In your GitHub repository create a file [`.github/workflows/action_server.yml`](https://github.com/RasaHQ/action-server-gha/blob/master/examples/action_server.yml).

The GitHub Action workflow below builds a new docker image every time files inside the `actions/` directory have changed and the changes are pushed into the `main` branch.

```yaml
on:
  push:
    branches:
      - main
    paths:
    - 'actions/**'

jobs:
  build_and_deploy:
    runs-on: ubuntu-latest
    name: Build Action Server image and upgrade Rasa X deployment
    steps:
    - name: Checkout repository
      uses: actions/checkout@v2

    - id: action_server
      name: Build an action server with a custom actions
      uses: RasaHQ/action-server-gha@master
      # Full list of parameters: https://github.com/RasaHQ/action-server-gha/tree/master#input-arguments
      with:
        docker_image_name: 'account_username/repository_name'
        docker_registry_login: ${{ secrets.DOCKER_HUB_LOGIN }}
        docker_registry_password: ${{ secrets.DOCKER_HUB_PASSWORD }}
        # More details about github context:
        # https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context
        #
        # github.sha - The commit SHA that triggered the workflow run
        docker_image_tag: ${{ github.sha }}
```

3. Push your changes to the `main` branch. After changes are pushed, the workflow will build and push a new image into the DockerHub registry.

4. Now, you can use your new brand docker image.

5. You can also extend your workflow, so that you do not have to manually update your Rasa X deployment. The example below shows how to extend your workflow with an additional step that updates a Rasa X [Helm Chart](https://rasa.com/docs/rasa-x/installation-and-setup/customize/#adding-a-custom-action-server) deployment.

```yaml
on:
  push:
    branches:
      - main

jobs:
  build_and_deploy:
    runs-on: ubuntu-latest
    name: Build Action Server image and upgrade Rasa X deployment
    steps:
    [..]

    # This step shows only the example of output parameter usage
    # and it's not focused on deployment itself.
    - name: "Upgrade a Rasa X deployment"
      run: |
        helm upgrade --install --reuse-values \
          --set app.name=${{ steps.action_server.outputs.docker_image_name }} \
          --set app.tag=${{ steps.action_server.outputs.docker_image_tag }} rasa rasa-x/rasa-x
```

As you can see it's possible to use output variables from the `action_server` step. The `steps.action_server.outputs.docker_image_name` variable returns
a docker image name and the `steps.action_server.outputs.docker_image_tag` variable returns a docker image tag.

More examples on how to use and customize [Rasa GitHub Actions](https://github.com/RasaHQ/action-server-gha) you can find in the [Rasa GitHub Actions](https://github.com/RasaHQ/action-server-gha) repository.

#### Manually Building an Action Server

To create your image:

1. Make sure your actions are defined in `actions/actions.py`. The `rasa/rasa-sdk`
  image will automatically look for the actions in this file.

2. If your actions have any extra dependencies, create a list of them in a file,
   `actions/requirements-actions.txt`.

3. Create a file named `Dockerfile` in your project directory,
   in which you'll extend the official SDK image, copy over your code, and add any custom dependencies (if necessary).
   For example:

   <pre><code parentName="pre" className="language-python">
   {`# Extend the official Rasa SDK image
   FROM rasa/rasa-sdk:${variables.rasa_sdk_version}

   # Use subdirectory as working directory
   WORKDIR /app

   # Copy any additional custom requirements, if necessary (uncomment next line)
   # COPY actions/requirements-actions.txt ./

   # Change back to root user to install dependencies
   USER root

   # Install extra requirements for actions code, if necessary (uncomment next line)
   # RUN pip install -r requirements-actions.txt

   # Copy actions folder to working directory
   COPY ./actions /app/actions

   # By best practices, don't run the code with root user
   USER 1001`}</code></pre>

You can then build the image via the following command:

```bash
docker build . -t <account_username>/<repository_name>:<custom_image_tag>
```

The `<custom_image_tag>` should reference how this image will be different from others. For
example, you could version or date your tags, as well as create different tags that have different code for production
and development servers. You should create a new tag any time you update your code and want to re-deploy it.

### Using your Custom Action Server Image

If you're building this image to make it available from another server,
for example a Rasa X or Rasa Enterprise deployment, you should push the image to a cloud repository.

This documentation assumes you are pushing your images to [DockerHub](https://hub.docker.com/).
DockerHub will let you host multiple public repositories and
one private repository for free. Be sure to first [create an account](https://hub.docker.com/signup/)
and [create a repository](https://hub.docker.com/signup/) to store your images. You could also push images to
a different Docker registry, such as [Google Container Registry](https://cloud.google.com/container-registry),
[Amazon Elastic Container Registry](https://aws.amazon.com/ecr/), or
[Azure Container Registry](https://azure.microsoft.com/en-us/services/container-registry/).

You can push the image to DockerHub via:

```bash
docker login --username <account_username> --password <account_password>
docker push <account_username>/<repository_name>:<custom_image_tag>
```

To authenticate and push images to a different container registry, please refer to the documentation of
your chosen container registry.

How you reference the custom action image will depend on your deployment. Pick the relevant documentation for
your deployment:

* [Server Quick-Install](https://rasa.com/docs/rasa-x/installation-and-setup/customize/#quick-install-script-customizing)

* [Helm Chart](https://rasa.com/docs/rasa-x/installation-and-setup/customize/#adding-a-custom-action-server)

* [Docker Compose](https://rasa.com/docs/rasa-x/installation-and-setup/customize/#connecting-a-custom-action-server)

* [Rasa Open Source Only](./docker/deploying-in-docker-compose.mdx#using-docker-compose-to-run-multiple-services)
